--- title: "06-Agent Skill 深度指南：Claude Code 模块化能力标准" created: 2026-01-20 tags: - 博客 aliases: - Agent Skill 深度指南：Claude Code 模块化能力标准 --- # Agent Skill 深度指南：Claude Code 模块化能力标准 ## **〇、概述与定位** ### **什么是 Agent Skill？** **Agent Skill**（又称 Claude Skill）是 Anthropic 推出的一种**基于文件系统的模块化能力标准**。它本质上是一种"渐进式披露"（Progressive Disclosure）的提示词管理机制，用于解决传统 System Prompt 的效率与可维护性问题。 ### **解决的核心痛点** | **传统方案** | **问题** | **Agent Skill 解决方式** | | --- | --- | --- | | 单一长 System Prompt | Token 浪费、上下文污染 | 分层加载，按需读取 | | 硬编码指令 | 难以复用、版本混乱 | 文件系统管理，模块化封装 | | 能力无边界 | 模型混淆、执行不精准 | 明确触发条件与执行边界 | ### **生态兼容性** Agent Skill 正在成为 AI 编程工具的事实标准： | **工具** | **支持状态** | **备注** | | --- | --- | --- | | **Claude Code** | ✅ 原生支持 | Anthropic 官方实现 | | **Cursor** | ✅ 支持 | 通过 `.cursorrules` 或 Skills 目录 | | **Codex CLI** | ✅ 支持 | OpenAI 的命令行编程助手 | | **OpenCode** | ✅ 支持 | 开源 AI 编程工具 | | **Windsurf** | ⚠️ 部分支持 | 通过自定义规则文件 | --- ## **一、核心概念：三层架构模型** ### **1.1 核心比喻：一本"带目录的书"** 传统的 System Prompt 将所有规则一次性注入 AI，既浪费 Token 又容易造成模型混淆。Agent Skill 采用分层管理策略： text ``` ┌─────────────────────────────────────────────────────────────────┐ │ Agent Skill 架构 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 第1层：元数据 (Metadata) ≈ 书的目录 │ │ │ │ ──────────────────────────────────────────────────────── │ │ │ │ • 内容：name + description │ │ │ │ • 加载：✅ 始终加载（启动时） │ │ │ │ • Token：极低消耗（约 50-100 tokens/skill） │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ 匹配触发 │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 第2层：指令 (Instructions) ≈ 书的正文 │ │ │ │ ──────────────────────────────────────────────────────── │ │ │ │ • 内容：Prompt、操作步骤、约束条件 │ │ │ │ • 加载：⚡ 按需加载（触发时） │ │ │ │ • Token：中等消耗（根据指令复杂度） │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ 执行引用 │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 第3层：资源 (Resources) ≈ 书的附录 │ │ │ │ ──────────────────────────────────────────────────────── │ │ │ │ • 内容：scripts/、templates/、assets/ │ │ │ │ • 加载：📂 按需调用（指令执行时） │ │ │ │ • Token：仅在使用时计入 │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### **1.2 各层详细说明** #### **第1层：元数据 (Metadata)** ```yaml --- name: csv-data-summarizer description: 使用 Python 和 pandas 分析 CSV 文件，生成统计摘要并绘制可视化图表。 metadata: version: 2.1.0 author: your-name dependencies: python>=3.8, pandas>=2.0.0 --- ``` | **字段** | **必填** | **说明** | | --- | --- | --- | | `name` | ✅ 是 | 技能唯一标识符，建议使用 kebab-case | | `description` | ✅ 是 | **关键字段**：Claude 根据此描述判断是否触发技能 | | `metadata.version` | 否 | 版本号，便于追踪更新 | | `metadata.dependencies` | 否 | 依赖声明，用于环境检查 | > *⚠️ **关键提示**：*`description` *的质量直接决定触发精准度。应使用**具体、可匹配的关键词**，避免模糊表述。* #### **第2层：指令 (Instructions)** 位于 SKILL.md 的 Frontmatter 下方，使用 Markdown 格式编写： ```markdown # CSV Data Summarizer ## When to Use (触发时机) 当用户满足以下条件时使用此 Skill： - 上传或引用了一个 CSV 文件 - 要求对表格数据进行摘要、分析或可视化 ## Critical Behavior (核心行为准则) ⚠️ **绝对准则**： 1. 禁止询问用户意图，直接执行分析 2. 自动生成所有相关图表 ... ``` #### **第3层：资源 (Resources)** ``` 📂 skill-name/ ├── 📄 SKILL.md ├── 📂 scripts/ # 可执行脚本 │ ├── analyze.py │ └── visualize.py ├── 📂 templates/ # 输出模板 │ └── report_format.md ├── 📂 assets/ # 静态资源 │ └── logo.png └── 📂 examples/ # Few-shot 示例 └── sample_input.csv ``` ### **1.3 与 MCP 的协作关系** | **组件** | **职责** | **类比** | | --- | --- | --- | | **Agent Skill** | 定义 SOP（标准作业程序）：何时做、怎么做 | 操作手册 | | **MCP (Model Context Protocol)** | 提供工具接口：文件读写、API 调用、命令执行 | 工具箱 | ``` 用户请求 → Skill 匹配 → 加载指令 → 调用 MCP 工具 → 执行任务 → 返回结果 ``` --- ## **二、配置指南：从零开始** ### **2.1 前置条件** - ✅ 已安装 Claude Code（`npm install -g @anthropic-ai/claude-code` 或官方安装方式） - ✅ 已完成基础配置（API Key 或模型代理） - ✅ 了解基本的终端操作 ### **2.2 第一步：建立技能库目录** Claude Code 启动时自动扫描以下路径： | **操作系统** | **路径** | | --- | --- | | **Windows** | `C:\Users\<用户名>\.claude\skills\` | | **macOS/Linux** | `~/.claude/skills/` | **标准目录结构**： ``` ~/.claude/skills/ # 技能库根目录 │ ├── 📂 pdf-summary/ # 技能包 1 │ ├── 📄 SKILL.md # 🔴 必需：技能定义文件（必须大写） │ ├── 📂 scripts/ # 可执行脚本 │ │ └── 🐍 extract.py │ └── 📂 templates/ # 输出模板 │ └── 📄 format.txt │ ├── 📂 git-automator/ # 技能包 2 │ └── 📄 SKILL.md │ └── 📂 code-reviewer/ # 技能包 3 ├── 📄 SKILL.md └── 📂 examples/ └── 📄 review_samples.md ``` **命名规范**： - 技能包文件夹：使用 `kebab-case`（如 `pdf-summary`） - SKILL.md：必须**全大写** `SKILL.md` - 脚本文件：使用 `snake_case`（如 `extract_text.py`） ### **2.3 第二步：编写 SKILL.md** #### **完整模板** ```markdown --- # ════════════════════════════════════════════════════════════════ # 第1层：元数据区 (Metadata) # 作用：Claude 启动时只读取这部分，用于判断是否触发此技能 # ════════════════════════════════════════════════════════════════ name: csv-data-summarizer description: | 使用 Python 和 pandas 分析 CSV 文件，生成统计摘要并绘制快速可视化图表。 支持：数据清洗、缺失值分析、分布统计、相关性热力图。 metadata: version: 2.1.0 author: your-name dependencies: - python>=3.8 - pandas>=2.0.0 - matplotlib>=3.5.0 tags: - data-analysis - visualization - csv --- # CSV Data Summarizer ## 📌 When to Use (触发时机) 当用户满足以下**任一**条件时使用此 Skill： - 上传或引用了一个 CSV 文件 - 要求对表格数据进行摘要、分析或可视化 - 想要了解数据的结构和质量 - 提及关键词：数据分析、表格处理、统计摘要 ## ⚠️ Critical Behavior (核心行为准则) ### 绝对禁止 1. ❌ **禁止询问用户意图**：不要问"你想让我做什么？"或提供选项菜单 2. ❌ **禁止部分执行**：必须完成完整的分析流程 3. ❌ **禁止忽略错误**：遇到数据问题必须报告，而非静默跳过 ### 必须执行 1. ✅ **立即全量分析**：自动运行分析、生成所有相关图表 2. ✅ **智能适配**：根据数据内容（销售、客户、财务等）自动决定分析方向 3. ✅ **结果可视化**：至少生成 2 种图表（分布图 + 相关性/趋势图） ## 🔄 Automatic Steps (自动化步骤) 步骤 1: 加载与检查 ├── 读取 CSV 到 pandas DataFrame ├── 检查编码（UTF-8/GBK 自动识别） └── 报告行数、列数 步骤 2: 结构识别 ├── 自动判断列类型（日期、数值、分类） ├── 识别主键候选列 └── 检测数据质量问题 步骤 3: 执行分析 ├── 数值列：统计描述（均值、中位数、标准差） ├── 分类列：频率分布 ├── 日期列：时间范围、趋势 └── 相关性：数值列间的相关矩阵 步骤 4: 生成输出 ├── 文本摘要：一段话概述数据特征 ├── 统计表格：关键指标汇总 ├── 可视化：分布图 + 热力图/趋势图 └── 问题报告：缺失值、异常值警告 ## 📋 Output Format (输出格式) ```markdown ## 📊 数据概览 - 文件：{filename} - 行数：{rows} | 列数：{columns} - 时间范围：{date_range}（如适用） ## 📈 统计摘要 | 列名 | 类型 | 非空率 | 均值/众数 | 范围/类别数 | |------|------|--------|-----------|-------------| | ... | ... | ... | ... | ... | ## ⚠️ 数据质量警告 - {warning_1} - {warning_2} ## 📉 可视化 [生成的图表将在此展示] Files 核心脚本 scripts/analyze.py - 核心分析逻辑，包含数据清洗和统计函数 scripts/visualize.py - 图表生成模块 配置文件 config/default_settings.json - 默认分析参数 示例资源 examples/sample_sales.csv - 销售数据示例 examples/expected_output.md - 期望输出参考 #### 简化模板（快速上手） ```markdown --- name: quick-translator description: 将文本翻译为指定语言，支持中英日韩法德西等主流语言。 --- # Quick Translator ## When to Use 用户请求翻译文本时触发。 ## Behavior 1. 自动检测源语言 2. 翻译为用户指定的目标语言（默认：英文） 3. 保持原文格式和语气 ## Output 提供：翻译结果 + 源语言识别 + 置信度评分 ``` ### **2.4 第三步：加载与验证** #### **重启 Claude Code** ```bash # 关闭当前会话，重新启动 claude ``` #### **验证加载状态** **方法 1：使用** `/doctor` **命令** ```bash > /doctor ``` 输出中会显示已加载的 Skills 列表。 **方法 2：直接询问** ```bash > 你现在加载了哪些 skills？列出它们的名称和描述。 ``` **方法 3：检查特定技能** ```bash > 你能处理 CSV 文件分析吗？如果能，是通过哪个 skill 实现的？ ``` ### **2.5 第四步：触发使用** 无需特殊命令，直接使用自然语言： ```bash > 帮我分析一下桌面上的 sales_2024.csv，我想看销售趋势 ``` Claude 会： 1. 匹配 `description` 中的关键词 → 命中 `csv-data-summarizer` 2. 加载 SKILL.md 的指令区 3. 按照 Automatic Steps 执行 4. 调用 `scripts/analyze.py`（如需要） 5. 返回结构化结果 --- ## **三、高级配置与技巧** ### **3.1 多 Skill 协作** 当一个任务需要多个 Skill 配合时： ```yaml --- name: report-generator description: 生成完整的数据分析报告，包含数据处理、可视化和 PPT 导出。 metadata: requires: # 声明依赖的其他 Skills - csv-data-summarizer - pptx-creation --- # Report Generator ## Workflow 1. 调用 `csv-data-summarizer` 分析数据 2. 整理分析结果 3. 调用 `pptx-creation` 生成演示文稿 ``` ### **3.2 条件触发优化** 使用**负向条件**避免误触发： ```markdown ## When NOT to Use - 用户只是询问 CSV 格式说明（不涉及具体文件） - 用户要求手动编辑 CSV（非分析任务） - 文件大小超过 100MB（应建议使用专业工具） ``` ### **3.3 Few-Shot 示例增强** 在 `examples/` 目录中提供示例，提升执行精准度： ```markdown # Examples ## 示例 1：销售数据分析 **用户输入**：分析这个销售表格 **期望输出**：[见 examples/sales_output.md] ## 示例 2：客户数据清洗 **用户输入**：帮我清理客户名单里的重复项 **期望输出**：[见 examples/cleanup_output.md] ``` ### **3.4 错误处理指令** ```markdown ## Error Handling ### 文件不存在 ``` ⚠️ 错误：找不到文件 {filename} 请检查： 1. 文件路径是否正确 2. 文件是否有读取权限 ``` ### 格式不支持 ``` ⚠️ 错误：不支持的文件格式 {extension} 此 Skill 仅支持：.csv, .tsv, .txt (制表符分隔) ```html   ``` --- ## **四、安全与权限管理** ### **4.1 安全风险警示** > *⚠️ **重要警告**：Agent Skill 的* `scripts/` *目录可包含**任意可执行代码**。从不受信任的来源下载 Skill 存在安全风险。* #### **风险矩阵** | **风险类型** | **危害程度** | **防护措施** | | --- | --- | --- | | 恶意脚本执行 | 🔴 严重 | 审查所有 `scripts/` 文件 | | 数据外泄 | 🔴 严重 | 检查网络请求代码 | | 文件系统破坏 | 🟠 中等 | 使用版本控制，定期备份 | | 依赖投毒 | 🟠 中等 | 验证 `requirements.txt` 来源 | ### **4.2 安全审查清单** 在使用第三方 Skill 前，执行以下检查： ```markdown ## 第三方 Skill 安全审查清单 ### 基础检查 - [ ] 来源是否可信（官方仓库/知名作者） - [ ] 是否有 README 说明其功能 - [ ] 社区反馈如何（Star/Issue） ### 代码审查 - [ ] scripts/ 目录下有哪些文件？ - [ ] 是否存在网络请求（requests/urllib）？ - [ ] 是否存在文件删除/修改操作（os.remove/shutil）？ - [ ] 是否存在 subprocess/os.system 调用？ ### 权限检查 - [ ] 是否要求管理员/root 权限？ - [ ] 是否访问敏感目录（~/.ssh, ~/.aws）？ ``` ### **4.3 权限模式详解** #### **默认模式（推荐）** 每次执行敏感操作前，Claude 会请求确认： ``` Claude: 我需要运行 scripts/analyze.py 来分析这个 CSV 文件。 是否允许？[y/n] ``` #### **完全自主模式** ```bash claude --dangerously-skip-permissions ``` | **特性** | **说明** | | --- | --- | | 效果 | Claude 可直接执行所有操作，无需确认 | | 风险 | 可能意外修改/删除文件、安装未知依赖、执行危险命令 | | 适用场景 | ① 完全信任的任务环境 ② 代码已提交 Git（可回滚） ③ 在沙盒/容器中运行 | **安全建议**： ```bash # 更安全的使用方式：在 Git 仓库中使用，便于回滚 cd your-project git add -A && git commit -m "checkpoint before claude" claude --dangerously-skip-permissions # 任务完成后检查变更 git diff ``` --- ## **五、实战案例：完整 Skill 库示例** ### **5.1 目录结构总览** ``` ~/.claude/skills/ │ ├── 📂 pptx-creation/ # 【Skill 1】PPT 演示文稿生成 │ ├── 📄 SKILL.md │ ├── 📂 scripts/ │ │ └── 🐍 generate_slides.py # 使用 python-pptx 生成 PPT │ └── 📂 assets/ │ ├── 📊 corporate_template.pptx # 公司模板 │ └── 📄 layout_config.json # 布局配置 │ ├── 📂 xlsx-analysis/ # 【Skill 2】Excel 数据分析 │ ├── 📄 SKILL.md │ ├── 📂 scripts/ │ │ ├── 🐍 clean_data.py # 数据清洗 │ │ └── 🐍 create_pivot.py # 透视表生成 │ └── 📂 examples/ │ ├── 📄 prompt_examples.txt # Few-shot 示例 │ └── 📉 sample_output.xlsx # 输出参考 │ ├── 📂 git-workflow/ # 【Skill 3】Git 操作自动化 │ ├── 📄 SKILL.md │ └── 📂 scripts/ │ ├── 🔧 smart_commit.sh # 智能提交信息生成 │ └── 🔧 pr_template.sh # PR 描述生成 │ ├── 📂 api-tester/ # 【Skill 4】API 测试助手 │ ├── 📄 SKILL.md │ ├── 📂 scripts/ │ │ └── 🐍 request_builder.py # 请求构造器 │ └── 📂 templates/ │ └── 📄 report_template.md # 测试报告模板 │ └── 📂 doc-generator/ # 【Skill 5】文档生成器 ├── 📄 SKILL.md └── 📂 templates/ ├── 📄 api_doc.md # API 文档模板 ├── 📄 readme.md # README 模板 └── 📄 changelog.md # 更新日志模板 ``` ### **5.2 示例 Skill：Git 工作流自动化** ```markdown --- name: git-workflow description: | 自动化 Git 工作流：智能生成 commit 信息、创建规范的 PR 描述、 分析代码变更并建议版本号更新。 metadata: version: 1.0.0 dependencies: - git>=2.30 --- # Git Workflow Automator ## When to Use - 用户完成代码修改，准备提交 - 用户请求生成 commit 信息 - 用户准备创建 Pull Request - 用户询问应该使用什么版本号 ## Commit Message Generation ### 规范 遵循 Conventional Commits 规范： (): [optional body] [optional footer(s)] ### Types - `feat`: 新功能 - `fix`: Bug 修复 - `docs`: 文档变更 - `style`: 代码格式（不影响逻辑） - `refactor`: 重构 - `perf`: 性能优化 - `test`: 测试相关 - `chore`: 构建/工具变更 ### 流程 1. 运行 `git diff --staged` 分析变更 2. 识别变更类型和范围 3. 生成符合规范的 commit 信息 4. 询问用户确认或修改 ## PR Description Generation ### 模板 ```markdown ## 变更概述 {一句话描述此 PR 的目的} ## 变更类型 - [ ] 新功能 - [ ] Bug 修复 - [ ] 重构 - [ ] 文档更新 ## 变更详情 {逐条列出主要修改} ## 测试说明 {如何验证这些变更} ## 相关 Issue Closes #{issue_number} Files scripts/smart_commit.sh - 分析 git diff 并生成 commit 信息 scripts/pr_template.sh - 生成 PR 描述 ``` ## 六、常见问题排查 ### Q1：Skill 没有被加载 **排查步骤**： ``` 检查路径是否正确 └── ~/.claude/skills//SKILL.md 检查文件名是否大写 └── 必须是 SKILL.md，不是 skill.md 检查 Frontmatter 格式 └── 必须以 --- 开头和结尾 └── YAML 语法是否正确（缩进、冒号后空格） 重启 Claude Code └── 关闭终端，重新运行 claude ``` ### Q2：Skill 加载了但不触发 **可能原因**： - `description` 与用户输入的关键词不匹配 - 存在其他 Skill 的 `description` 更匹配 **解决方案：** 1. 优化 `description`，使用更具体的关键词 2. 添加 `When to Use` 部分的详细触发条件 3. 测试时明确提及 Skill 名称："使用 csv-data-summarizer 分析这个文件" ### Q3：脚本执行失败 **排查清单**： - Python 版本是否满足 dependencies 要求 - 所需库是否已安装（`pip install -r requirements.txt`） - 脚本是否有执行权限（Linux/macOS：`chmod +x script.py`） - 脚本路径在 SKILL.md 中是否正确声明 ### Q4：如何调试 Skill 逻辑 ```bash # 方法 1：要求 Claude 显示推理过程 > 请分析这个 CSV 文件，并详细说明你调用了哪个 skill、执行了哪些步骤 # 方法 2：检查 skill 匹配 > 如果我说"帮我做个销售报表"，你会触发哪个 skill？为什么？ # 方法 3：手动测试脚本 cd ~/.claude/skills/csv-data-summarizer/scripts python analyze.py test_data.csv ``` --- ## **七、资源与参考** ### **官方资源** | **资源** | **链接** | | --- | --- | | Claude Code 文档 | | | Anthropic 官方 Skills | | | MCP 协议规范 | [https://modelcontextprotocol.io](https://modelcontextprotocol.io/) | ### **社区资源** | **资源** | **说明** | | --- | --- | | awesome-claude-skills | GitHub 上的社区 Skill 集合 | | r/ClaudeAI | Reddit 讨论社区 | ### **推荐学习路径** ``` 1. 入门：使用官方示例 Skill，理解结构 ↓ 2. 实践：基于模板创建自己的简单 Skill ↓ 3. 进阶：添加 scripts/ 实现复杂逻辑 ↓ 4. 高级：多 Skill 协作 + MCP 工具集成 ``` --- ## **八、快速参考卡片** ### **SKILL.md 结构速查** ``` ┌─────────────────────────────────────────────────┐ │ SKILL.md 标准结构 │ ├─────────────────────────────────────────────────┤ │ --- │ │ name: skill-name # 必填 │ │ description: ... # 必填，决定触发 │ │ metadata: # 可选 │ │ version: x.x.x │ │ dependencies: [...] │ │ --- │ │ │ │ # Skill Title │ │ ## When to Use # 触发条件 │ │ ## Critical Behavior # 核心行为 │ │ ## Automatic Steps # 执行步骤 │ │ ## Output Format # 输出格式 │ │ ## Error Handling # 错误处理 │ │ │ │ # Files # 资源声明 │ │ - scripts/xxx.py │ │ - templates/xxx.md │ └─────────────────────────────────────────────────┘ ``` ### **目录结构速查** ``` ~/.claude/skills/ └── skill-name/ # kebab-case 命名 ├── SKILL.md # 🔴 必需，大写 ├── scripts/ # 可执行脚本 ├── templates/ # 输出模板 ├── assets/ # 静态资源 └── examples/ # Few-shot 示例 ``` ### **安全检查速查** ``` 第三方 Skill 使用前： ├── ✅ 检查来源可信度 ├── ✅ 审查 scripts/ 下所有代码 ├── ✅ 检查是否有网络请求 ├── ✅ 检查是否有文件操作 └── ✅ 在沙盒/Git 环境中首次测试 ``` --- > ***持续更新提示**：Agent Skill 标准仍在快速演进中。建议关注：* > > - *Anthropic 官方博客* > - *Claude Code Release Notes* > - *GitHub anthropics/skills 仓库更新* ---